home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 14 / Mac Magazin and MacEasy Magazine CD - Issue 14.iso / Wissenschaft & Technik / StandardGetFolder 2.0 / Documentation / StandardGetFolder ReadMe next >
Text File  |  1995-07-15  |  7KB  |  133 lines
  1. Standard Get Folder ReadMe
  2. Text and Source Copyright © 1993–1995 Chris Larson (larson@kingston.cs.ucla.edu), all rights reserved                                                               
  3.  
  4. Standard Get Folder is a procedure which, go figure, allows a user to select a folder via the
  5. Standard File Package. Details about using the StandardGetFolder procedure can be found
  6. in the user’s guide; this document is simply a catch-all for everything I wanted to say but
  7. didn’t belong in the User’s Guide.
  8.  
  9.  
  10. Why Did I Do It?                                                                              
  11.  
  12. In the course of working on a project, I happened to download some existing code samples for
  13. folder selection via the standard file package. After examining the code in each and discovering
  14. errors and/or omissions in all of them (well, all the ones I looked at anyway; I’m not sure if I
  15. looked at every folder selection package available), I decided it was time to write my own. This
  16. package is the result of my efforts.
  17.  
  18.  
  19. Standard Get Folder Features                                                           
  20.  
  21. I tried to make StandardGetFolder do as much as I thought necessary to do the job right,
  22. handling some of the problems that were not implemented right (or at all) in the other
  23. packages I have examined.
  24.  
  25. n Internal Error Handling — Some other packages did no error checking or handling at all;
  26.       my routine handles any expected errors internally (just like the Standard File Package) and
  27.       only returns to the application when the user selects a folder or cancels the selection. (This
  28.       is not strictly true; the routine can return on an out-of-memory or resource not found error
  29.       but these conditions will be reported to the calling application.)
  30.  
  31. n Correct Handling of Activate and Update Events — Some of the routines I looked at didn’t
  32.       even update the Standard File Package dialogs correctly. These routines handle window
  33.       events correctly and even provide a hook to allow application windows to be updated while
  34.       modal dialogs are obscuring them (refer to the Technical Note TB 37 - Pending Update Perils
  35.       for details on this problem).
  36.  
  37. n Complete Support for Balloon Help — Completely missing from most everything I looked at,
  38.       balloon help is provided for every element in the Standard Get Folder dialogs.
  39.  
  40. n Easy Localization (I hope) — Other packages had string literals within the code and other
  41.       localization problems. I have stored all string literals as resources and employed the
  42.       International Utilities and Script Manager where appropriate (as opposed to using strcmp
  43.       for example). I have not had an opportunity to localize this package to any language other
  44.       than U.S. English (call me uncultured; I don’t speak any other language), so this remains
  45.       untested.
  46.  
  47. n Low Network Traffic — The method described in Inside Macintosh: Files for updating the
  48.       title of the select button causes a volume catalog query every time through the event loop,
  49.       resulting in a measurable amount of network traffic when selecting a folder on a remote
  50.       volume. My routine only re-examines the volume catalog when necessary, resulting in
  51.       a dramatic reduction in network traffic.
  52.  
  53. n Does Not Require the ANSI Libraries — All work is done by calling the Toolbox, thus
  54.       removing the need to link with the ANSI libraries. This resulted mostly from the attempt
  55.       to make localization possible (e.g. by not using strcmp) and also out of a concern for space.
  56.  
  57.  
  58. Standard Get Folder Problems                                                          
  59.  
  60. Cosmetic Bug with OpenWide and DialogView
  61.  
  62. OpenWide and DialogView modify Standard File Package dialog boxes to provide a larger area
  63. for displaying the file list. Both of these fail to place the buttons in the Standard Get Folder dialog
  64. in aesthetically pleasing locations. All functionality remains intact, this is simply a cosmetic bug.
  65.  
  66. Cosmetic Bug with Greg’s Buttons
  67.  
  68. Gerg’s Buttons is a control panel which allows the user to, among other things, replace the
  69. standard controls with 3-d controls. Greg’s Buttons (and any other INIT which replaces the
  70. system controls) fails to replace the New Folder button corrrectly. This is owing to the fact that
  71. I use a custom CDEF for handling this button. The New Folder button still functions properly,
  72. it just jooks a little weird.
  73.  
  74.  
  75. Other Information About Standard Get Folder                                
  76.  
  77. Requirements
  78.  
  79. Standard Get Folder needs at least System 7.0 to function correctly. It will make use of the added
  80. features of System Update 3.0 and/or System 7.5 if either is installed.
  81.  
  82. Testing
  83.  
  84. This package has been tested on a Macintosh Plus, Powerbook 160, and Power Macintosh 7100/80
  85. with system versions 7.0, 7.1 (with System Update 3.0), and 7.5 respectively.
  86.  
  87. Usage Rules
  88.  
  89. This package (source code and compiled derivatives) may be used in any shareware product (or
  90. other such stuff: freeware, postcardware, etc.) as long as you mention me in your credits (of
  91. course, a registered version of whatever you write using this package wouldn’t hurt either ;-). 
  92. This package is not in the public domain and may not be used in any public domain product in
  93. any fashion. This package may not be used in any commercial product without the expressed,
  94. written consent of the author.
  95.  
  96. Legal Stuff
  97.  
  98. This package is Copyright © 1993–1995 Chris Larson, all rights reserved. I have made a great
  99. effort to ensure that this package is free of bugs but I make no warranty, either implied or
  100. explicit, as to the functionality of this package. By using this package, the user assumes all
  101. responsibility for any damages caused by this package, either directly or indirectly.
  102.  
  103. Author
  104.  
  105. Chris Larson
  106. 5305 Parkmor Rd. #3
  107. Calabasas, CA  91302
  108.  
  109. Internet E-Mail (preferred) larson@kingston.cs.ucla.edu
  110.  
  111.  
  112. Standard Get Folder Version History                                                
  113.  
  114. Version 2.0 — July 3, 1995
  115.  
  116. Added the ability to specify a set of access privileges for desired folders, thus enabling the selection
  117. of write-only (drop) folders.
  118.  
  119. Added the New Folder button and supporting routines (mucho work).
  120.  
  121. Changed the pascal string routines to use those in <PLStringFuncs.h> instead of using the 680x0
  122. assembly routines used previously.
  123.  
  124. Changed the trap patch to C from 680x0 assembly so it can be compiled native for PPC.
  125.  
  126. Improved the internal error handling to rely much less on the Standard File Package dealing
  127. with errors itself.
  128.  
  129. Vastly improved the documentation.
  130.  
  131. Version 1.0 — August 1993
  132.  
  133. Initial release.